/*
 * Copyright (C) 2012  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.resources.impl;

import java.io.IOException;
import java.util.Locale;
import java.util.ResourceBundle;
import java.util.ResourceBundle.Control;

import nemos.resources.IResources;

/**
 * IControl : The control interface.
 * 
 * <p>
 * This interface is an adaptation of the {@link Control} class. It is an helper
 * for {@link IResources} generation, as {@link Control} is for
 * {@link ResourceBundle}s.
 * </p>
 * 
 * <p>
 * Each implementation of this service must define the types it handles. This is
 * done through the {@link #TYPE_PROPERTY} service property which accepts a
 * String, an array or a collection of String. Each String is the fully
 * qualified name of a supported type.
 * </p>
 * 
 * @author Romain DUBOIS
 */
public interface IControl {

    /** The type property name */
    String TYPE_PROPERTY = "nemos.resources.control.type"; //$NON-NLS-1$

    /**
     * Gets the time to live for a specific bundle from its base name and
     * locale.
     * 
     * @see Control#getTimeToLive(String, Locale)
     * 
     * @param pBaseName
     *            The base name of the resource bundle for which the expiration
     *            value is specified.
     * @param pLocale
     *            The locale of the resource bundle for which the expiration
     *            value is specified.
     * @return The time (0 or a positive millisecond offset from the cached
     *         time) to get loaded bundles expired in the cache,
     *         {@link Control#TTL_NO_EXPIRATION_CONTROL} to disable the
     *         expiration control, or {@link Control#TTL_DONT_CACHE} to disable
     *         caching.
     */
    long getTimeToLive(String pBaseName, Locale pLocale);

    /**
     * Test if a {@link ResourceBundle} created by this {@link IControl} needs
     * to be reloaded (file(s) may have been updated).
     * 
     * @see Control#needsReload(String, Locale, String, ClassLoader,
     *      ResourceBundle, long)
     * 
     * @param pBaseName
     *            The base bundle name of the resource bundle, a fully qualified
     *            class name
     * @param pLocale
     *            The locale for which the resource bundle should be
     *            instantiated
     * @param pFormat
     *            The resource bundle format to be loaded
     * @param pLoader
     *            The <code>ClassLoader</code> to use to load the bundle
     * @param pBundle
     *            The resource bundle instance that has been expired in the
     *            cache
     * @param pLoadTime
     *            the time when <code>bundle</code> was loaded and put in the
     *            cache
     * @return <code>true</code> if the expired bundle needs to be reloaded;
     *         <code>false</code> otherwise.
     */
    boolean needsReload(String pBaseName, Locale pLocale, String pFormat, ClassLoader pLoader,
            ResourceBundle pBundle, long pLoadTime);

    /**
     * Generate the resource bundle with the specified base name and for the
     * desired locale. For type safety, it is recommended to return an
     * implementation of the {@link IResources} interface supporting the
     * resources type described by <code>pFormat</code>.
     * 
     * @see Control#newBundle(String, Locale, String, ClassLoader, boolean)
     * 
     * @param pBaseName
     *            The base bundle name of the resource bundle, a fully qualified
     *            class name
     * @param pLocale
     *            The locale for which the resource bundle should be
     *            instantiated
     * @param pFormat
     *            The resource bundle format to be loaded
     * @param pLoader
     *            The <code>ClassLoader</code> to use to load the bundle
     * @param pReload
     *            The flag to indicate bundle reloading; <code>true</code> if
     *            reloading an expired resource bundle, <code>false</code>
     *            otherwise
     * @return The resource bundle instance, or <code>null</code> if none could
     *         be found.
     * @exception IllegalAccessException
     *                If the class or its nullary constructor is not accessible.
     * @exception InstantiationException
     *                If the instantiation of a class fails for some other
     *                reason.
     * @exception IOException
     *                If an error occurred when reading resources using any I/O
     *                operations
     */
    ResourceBundle newBundle(String pBaseName, Locale pLocale, String pFormat, ClassLoader pLoader,
            boolean pReload) throws IllegalAccessException, InstantiationException, IOException;
}
